home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SLSubmitJob.z / SLSubmitJob
Encoding:
Text File  |  2002-10-03  |  14.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))                   IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                    SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SLSubmitJob, SLSubmitJobFd, SLSubmitJobBuf, SLSubmitJobSimple - submit a
  10.      job for printing
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssppppoooooooollll....hhhh>>>>
  14.  
  15.      SSSSLLLLPPPPrrrriiiinnnnttttJJJJoooobbbb**** SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee,,,,
  16.                              ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,,
  17.                              iiiinnnntttt nnnnuuuummmm____ccccooooppppiiiieeeessss,,,, iiiinnnntttt ccccooooppppyyyy,,,,
  18.                              iiiinnnntttt mmmmaaaaiiiillll,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttiiiittttlllleeee,,,,
  19.                              ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ooooppppttttiiiioooonnnnssss))));;;;
  20.  
  21.      SSSSLLLLPPPPrrrriiiinnnnttttJJJJoooobbbb**** SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbbFFFFdddd((((iiiinnnntttt ffffiiiilllleeee____ddddeeeesssscccc,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,,
  22.                                iiiinnnntttt nnnnuuuummmm____ccccooooppppiiiieeeessss,,,, iiiinnnntttt ccccooooppppyyyy,,,,
  23.                                iiiinnnntttt mmmmaaaaiiiillll,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttiiiittttlllleeee,,,,
  24.                                ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ooooppppttttiiiioooonnnnssss))));;;;
  25.  
  26.      SSSSLLLLPPPPrrrriiiinnnnttttJJJJoooobbbb**** SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbbBBBBuuuuffff((((ccccoooonnnnsssstttt vvvvooooiiiidddd ****bbbbuuuuffffffffeeeerrrr,,,, ssssiiiizzzzeeee____tttt aaaammmmoooouuuunnnntttt,,,,
  27.                                 ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr,,,, iiiinnnntttt nnnnuuuummmm____ccccooooppppiiiieeeessss,,,,
  28.                                 iiiinnnntttt ccccooooppppyyyy,,,, iiiinnnntttt mmmmaaaaiiiillll,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ttttiiiittttlllleeee,,,,
  29.                                 ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ooooppppttttiiiioooonnnnssss))));;;;
  30.  
  31.      SSSSLLLLPPPPrrrriiiinnnnttttJJJJoooobbbb**** SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbbSSSSiiiimmmmpppplllleeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee))));;;;
  32.  
  33. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  34.      _S_L_S_u_b_m_i_t_J_o_b submits a file to be printed using the current default
  35.      spooling system.
  36.  
  37.      _S_L_S_u_b_m_i_t_J_o_b_S_i_m_p_l_e also submits a file for printing but uses default
  38.      values for all printing options.
  39.  
  40.      _S_L_S_u_b_m_i_t_J_o_b_F_d submits the contents of the file specified by a file
  41.      descriptor for printing.
  42.  
  43.      _S_L_S_u_b_m_i_t_J_o_b_B_u_f submits the contents of the specified buffer for printing.
  44.  
  45.      _f_i_l_e_n_a_m_e       Specifies the pathname of the file to be printed. This
  46.                     string can specify multiple files by separating the
  47.                     filenames with one or more whitespace characters. Wildcard
  48.                     characters may be used but shell job control meta
  49.                     characters such as ";" and "&" must not be used.  Note
  50.                     that it is the responsibility of the caller to verify that
  51.                     _f_i_l_e_n_a_m_e does not contain characters that would be
  52.                     interpreted as job control meta characters. _l_i_b_s_p_o_o_l does
  53.                     not perform this verification.
  54.  
  55.      _f_i_l_e__d_e_s_c      Specifies a file descriptor open for reading.
  56.  
  57.      _b_u_f_f_e_r         Specifies a buffer to be printed.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))                   IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                    SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))
  71.  
  72.  
  73.  
  74.      _a_m_o_u_n_t         Specifies the number of bytes in _b_u_f_f_e_r.
  75.  
  76.      _p_r_i_n_t_e_r        Specifies the name of the printer on which the job is to
  77.                     be printed.  If _p_r_i_n_t_e_r is NNNNUUUULLLLLLLL, the default printer for
  78.                     the current spooling system is used.
  79.  
  80.      _n_u_m__c_o_p_i_e_s     Specifies the number of copies of the job that are to be
  81.                     printed.  The value specified must be greater than 0.
  82.  
  83.      _c_o_p_y           If set to 1, this parameter specifies that the file to be
  84.                     printed should be copied to the spooling directory for the
  85.                     destination printer. If set to 0, a link will be created
  86.                     in the spooling directory pointing to the real file. If a
  87.                     link is created, the user should not change or delete the
  88.                     file until it has been printed.
  89.  
  90.      _m_a_i_l           If set to 1, this parameter indicates that mail should be
  91.                     sent to the user upon completion of printing. If set to 0,
  92.                     no mail will be sent.
  93.  
  94.      _t_i_t_l_e          Specifies a title to be printed on the banner page of the
  95.                     print job. If set to NNNNUUUULLLLLLLL, the system dependent default
  96.                     title, if any, will be printed.
  97.  
  98.      _o_p_t_i_o_n_s        The file(s) specified to this function are submitted to
  99.                     the spooling system print command corresponding to the
  100.                     current default spooling system. For System V, _S_L_S_u_b_m_i_t_J_o_b
  101.                     executes _l_p(_1) and for BSD, the function executes _l_p_r(_1).
  102.                     Each of these spooling system commands allows option flags
  103.                     and parameters not covered by the _S_L_S_u_b_m_i_t_J_o_b formal
  104.                     parameter list. The _o_p_t_i_o_n_s string provides the means to
  105.                     pass parameters that are spooling system specific.  The
  106.                     string specified is passed unchanged to the appropriate
  107.                     spooling system print command. If there are no options to
  108.                     be passed to the spooling system, this parameter can be
  109.                     set to NNNNUUUULLLLLLLL.
  110.  
  111.      The _S_L_S_u_b_m_i_t_J_o_b_S_i_m_p_l_e function uses the following default printing
  112.      options:
  113.  
  114.                     PPPPrrrriiiinnnnttttiiiinnnngggg OOOOppppttttiiiioooonnnn             DDDDeeeeffffaaaauuuulllltttt VVVVaaaalllluuuueeee
  115.                     ___________________________________________
  116.                     Printer                     Default printer
  117.                     Number of copies            1
  118.                     Copy or link file           Link
  119.                     Send mail on completion     No mail
  120.                     Title                       None
  121.                     Spooler dependent options   None
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))                   IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                    SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))
  137.  
  138.  
  139.  
  140. RETURN VALUE
  141.      If an error has occurred during execution of the function, NNNNUUUULLLLLLLL is
  142.      returned. If execution was successful, a pointer to a _S_L_P_r_i_n_t_J_o_b
  143.      structure is returned. This structure contains detailed information about
  144.      the print job. The _S_L_P_r_i_n_t_J_o_b structure is defined as:
  145.  
  146.           typedef struct _slPrintJob {
  147.               unsigned int spooler;  /* Spooling system for job */
  148.                                      /* e.g. SL_SPOOLER_BSD */
  149.               char *printer;         /* Local name of printer */
  150.               char *filename;        /* File(s) to be printed */
  151.               char *username;        /* Job owner user name */
  152.               char *job_id;          /* Job ID, where available */
  153.               time_t time_stamp;     /* Time when submitted */
  154.           } SLPrintJob;
  155.  
  156.  
  157. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  158.      All job submittal functions will fail under the following general
  159.      circumstances.
  160.  
  161.      SL_ERR_FIND_SPOOLER      An error occurred while attempting to determine
  162.                               the available printer spooling systems.
  163.  
  164.      SL_ERR_NO_SPOOLERS       There are no printer spooling systems available.
  165.  
  166.  
  167.      SL_ERR_NO_DEF_PRINTER    There is no default printer registered with the
  168.                               printer spooling system.
  169.  
  170.      SL_ERR_SPOOLER_ERROR     A printer spooling system error has occurred.
  171.  
  172.      SL_ERR_BAD_PRINTER_NAME  The printer name specified is either an empty
  173.                               string (""), or a string consisting entirely of
  174.                               whitespace.
  175.  
  176.      In addition to the general circumstances, _S_L_S_u_b_m_i_t_J_o_b_S_i_m_p_l_e and
  177.      _S_L_S_u_b_m_i_t_J_o_b will fail under the following circumstances.
  178.  
  179.      SL_ERR_NO_FILENAME       The filename specified is either a NULL pointer,
  180.                               an empty string ("") or a string consisting
  181.                               entirely of whitespace.
  182.  
  183.      _S_L_S_u_b_m_i_t_J_o_b, _S_L_S_u_b_m_i_t_J_o_b_F_d and _S_L_S_u_b_m_i_t_J_o_b_B_u_f will fail if the following
  184.      problems are detected in the job submittal options.
  185.  
  186.      SL_ERR_NUM_COPIES        An invalid number of copies to print has been
  187.                               specified.
  188.  
  189.      SL_ERR_JOB_COPY          An invalid job copy/link parameter has been
  190.                               specified.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))                   IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                    SSSSLLLLSSSSuuuubbbbmmmmiiiittttJJJJoooobbbb((((3333))))
  203.  
  204.  
  205.  
  206.      SL_ERR_MAIL              An invalid mail parameter has been specified.
  207.  
  208.      _S_L_S_u_b_m_i_t_J_o_b_F_d will fail if:
  209.  
  210.      SL_ERR_BAD_FD            An invalid file descriptor has been specified.
  211.  
  212.      and _S_L_S_u_b_m_i_t_J_o_b_B_u_f will fail if:
  213.  
  214.      SL_ERR_BAD_BUF           An invalid buffer pointer or buffer size has
  215.                               been specified.
  216.  
  217. WWWWAAAARRRRNNNNIIIINNNNGGGG
  218.      The print job pointer returned by the functions points to static storage
  219.      within _l_i_b_s_p_o_o_l. Subsequent calls to the functions will change the
  220.      contents of the job structure. To preserve a job structure, copy the
  221.      structure and contents to a user buffer.
  222.  
  223. NNNNOOOOTTTTEEEESSSS
  224.      All mention of "fields" refers to the fields of the _S_L_P_r_i_n_t_J_o_b structure.
  225.  
  226.      1.   Under the  BSD spooling system, the _j_o_b__i_d field will be set to
  227.           NNNNUUUULLLLLLLL.  To determine the job ID under BSD spooling, the printer queue
  228.           must be examined manually.
  229.  
  230.      2.   Under System V spooling, the _j_o_b__i_d field will be set to NNNNUUUULLLLLLLL if the
  231.           -_s flag is passed using the _o_p_t_i_o_n_s parameter.
  232.  
  233.      3.   The _u_s_e_r_n_a_m_e field contains the name of the user submitting the job
  234.           based on the real user id, not the effective user ID. This is
  235.           because the spooling system determines job ownership based on real
  236.           user ID.
  237.  
  238.      4.   The _t_i_m_e__s_t_a_m_p field contains the value returned by the time(2)
  239.           function. Refer to the time(2) and ctime(3) man pages for
  240.           information about the time value and how it may be converted to a
  241.           time string.
  242.  
  243. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  244.      SLCancelJob(3), SLGetQueue(3), SLPerror(3), libspool(3), lp(1), lpr(1)
  245.      time(2), ctime(3)
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.